docs/development/Configuration Format.md

   1 # Configuration Format
   2
   3 The configuration format and external protocol use some of the same concepts
   4 as SAE J1939.  A parameter group (PG) is a set of parameters belonging
   5 to the same topic and are stored and sent together.  A parameter group
   6 instance has a unique parameter group number (PGN).  Each parameter
   7 also has a suspect parameter number (SPN) which can be used to get or
   8 set a parameter directly.
   9
  10 When used as on-wire formats structures should be packed to give the
  11 same in storage, in memory, and on-wire format.  However care must be taken
  12 over memory alignment issues when packing structures.
  13
  14 The PGs can be defined on a system-wide basis on a profile specific basis.
  15 profiles can be activated on the fly.
  16
  17 The storage consists of a header, zero or more PGs, a footer and a checksum.
  18 To keep the RAM usage low, the parameters are written directly to flash
  19 which means that things that are only known at the end, such as the
  20 size are stored in the footer. The checksum is written after the footer.
  21
  22 The header holds:
  23
  24 * The format number.  This is bumped on incompatible changes.
  25
  26 Each stored PG holds:
  27
  28 * The size of this record
  29 * The PGN
  30 * Version number
  31 * Profile number
  32 * Flags
  33 * The record format.  This is bumped on incompatible changes.
  34 * The PG data
  35
  36 The footer holds:
  37
  38 * A zero to mark the end of data
  39
  40 The checksum is based on the header, PGs, and footer.
  41
  42 The PG registrations hold similar but not identical information (e.g. the profile
  43 number is not known until it is stored).
  44
  45 ## Initialiion function.
  46
  47 All fields are reset to 0 upon initialisation and then if a reset function is
  48 defined for the group then initial settings can be defined by the system.
  49
  50 ## Upgrading
  51
  52 Upgrades are done at the PG level and are detected by a difference in
  53 size or version.  New fields can be added to the end of the parameter group.
  54 The reset and initialisation function is called before upgrading so new
  55 fields will first be reset to 0 and then initialised by the system if defined.
  56
  57 Note: Currently the code does not check the version field.
  58
  59 ## Downgrading
  60
  61 Downgrades are done at the PG level.  Any trailing, unrecognised
  62 fields will be silently dropped on load.  Saving the config back to
  63 flash will discard these unrecognised fields.
  64
  65 ## Incompatible changes
  66
  67 An incompatible change is where a field is inserted, deleted from the
  68 middle, reordered, resized (including changing the size of a contained array),
  69 or has the meaning changed.  Such changes should be handled by bumping the
  70 PG version field or allocating a new PGN.